/*
 *  Copyright 2010 Andrew Kroh
 *
 *  Kroh-IO is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Kroh-IO is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package kroh.io;

import java.io.InputStream;
import java.io.OutputStream;
import java.io.IOException;

/**
 * <p>
 * A communications port. CommPort is an abstract class that describes a
 * communications port made available by the underlying system. It includes
 * high-level methods for controlling I/O that are common to different kinds of
 * communications ports. SerialPort and ParallelPort are subclasses of CommPort
 * that include additional methods for low-level control of physical
 * communications ports.
 * <p>
 * There are no public constructors for CommPort. Instead an application should
 * use the static method CommPortIdentifier.getPortIdentifiers to generate a
 * list of available ports. It then chooses a port from this list and calls
 * CommPortIdentifier.open to create a CommPort object. Finally, it casts the
 * CommPort object to a physical communications device class like SerialPort or
 * ParallelPort.
 * <p>
 * After a communications port has been identified and opened it can be
 * configured with the methods in the low-level classes like SerialPort and
 * ParallelPort. Then an IO stream can be opened for reading and writing data.
 * Once the application is done with the port, it must call the close method.
 * Thereafter the application must not call any methods in the port object.
 * Doing so will cause a java.lang.IllegalStateException to be thrown.
 */
public abstract class CommPort
{
    protected String name;

    /**
     * Gets the name of the communications port. This name should correspond to
     * something the user can identify, like the label on the hardware.
     * 
     * @return name of the port
     */
    public String getName()
    {
        return name;
    }

    /**
     * Returns a String representation of this communications port.
     * 
     * @return String representation of the port
     */
    public String toString()
    {
        StringBuilder sb = new StringBuilder();

        sb.append("[CommPort]\n");
        sb.append("    Name: " + name);

        return sb.toString();
    }

    public abstract InputStream getInputStream() throws IOException;

    public abstract OutputStream getOutputStream() throws IOException;

    /**
     * Closes the communications port. The application must call close when it
     * is done with the port. Notification of this ownership change will be
     * propagated to all classes registered using addPortOwnershipListener.
     */
    public void close()
    {
        try
        {
            CommPortIdentifier cp = CommPortIdentifier.getPortIdentifier(this);
            
            if (cp != null)
            {
                // Mark the port as closed and fire the ownership change
                // event in the CommPortIdentifier:
                cp.close();
            }
        } 
        catch (NoSuchPortException e)
        {
            throw new IllegalStateException(e);
        }
    }

    public abstract void enableReceiveThreshold(int thresh)
            throws UnsupportedCommOperationException;

    public abstract void disableReceiveThreshold();

    public abstract int getReceiveThreshold();

    public abstract boolean isReceiveThresholdEnabled();

    public abstract void enableReceiveTimeout(int time)
            throws UnsupportedCommOperationException;

    public abstract void disableReceiveTimeout();

    public abstract boolean isReceiveTimeoutEnabled();

    public abstract int getReceiveTimeout();

    public abstract void enableReceiveFraming(int f)
            throws UnsupportedCommOperationException;

    public abstract void disableReceiveFraming();

    public abstract boolean isReceiveFramingEnabled();

    public abstract int getReceiveFramingByte();

    public abstract void setInputBufferSize(int size);

    public abstract int getInputBufferSize();

    public abstract void setOutputBufferSize(int size);

    public abstract int getOutputBufferSize();
}
